<html>
<head>
<title>About Jasmin</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
<table>
<tr><td width=550>
<center>
<p><img src=jasmin_icon.jpg></p>
<p>
<div class="h1">ABOUT JASMIN</div>
Jonathan Meyer, July 1996
</p>
</center>

<h1>Introduction</h1>

This document tries to answer some questions you might have
about Jasmin. In particular, several people have asked me what
Jasmin is, why they might use Jasmin, and why I wrote it in the
first place. I've tried to give some answers to these questions
below.<p>

<h1>Jasmin Assembler</h1>

Jasmin is a Java Assembler Interface. It takes ASCII descriptions for Java
classes, written in a simple assembler-like syntax using the Java Virtual
Machine instructions set. It converts them into binary Java class files 
suitable for loading into a Java interpreter.<p>

To give you a flavor, here is the Jasmin assembly code for HelloWorld:<p>

<pre>
    .class public HelloWorld
    .super java/lang/Object

    ;
    ; standard initializer (calls java.lang.Object's initializer)
    ;
    .method public &lt;init&gt;()V
       aload_0
       invokenonvirtual java/lang/Object/&lt;init&gt;()V
       return
    .end method

    ;
    ; main() - prints out Hello World
    ;
    .method public static main([Ljava/lang/String;)V
       .limit stack 2   ; up to two items can be pushed

       ; push System.out onto the stack
       getstatic java/lang/System/out Ljava/io/PrintStream;

       ; push a string onto the stack
       ldc "Hello World!"

       ; call the PrintStream.println() method.
       invokevirtual java/io/PrintStream/println(Ljava/lang/String;)V

       ; done
       return
    .end method

</pre>

<p>
Jasmin was originally created as a companion to the book "Java Virtual Machine", 
written by Jon Meyer and Troy Downing and published by O'Reilly Associates. The
book is now out of print. Jasmin survives as a SourceForge Open Source project.
</p>

<h1>Motivation for Jasmin</h1>

<p>
Jasmin was written because, at the time that we wrote the Java Virtual Machine
book for O'Reilly, Sun had not published an assembler format for the 
Java virtual machine. 
</p>

<p>
Generating a binary Java .class file is pretty fiddly. Its like
creating an a.out (or .exe) file by hand. Even using a Java package like 
JAS (a Java API for creating class files, used internally by Jasmin and written by KB Sriram), you 
need to know a lot about the philosophy of the Java Virtual
Machine before you can write something at the Virtual
Machine level and generate a Java class. <p>

We wanted something that made it very easy for a student or programmer
to explore the Java Virtual Machine, or write a new language 
which targets the VM, without getting into the details of constant
pool indices, attribute tables, and so on.<p>

<p>
Creating a Java assembler seemed like a good solution.
</p>

<p>
Unfortunately, Sun has not seen the need to define a standard Java 
assembler format, and has not released tools perform Java assembly.
</p>

<p>Sun does provide a javap program which can print the assembly code
in a class file. However, the javap output is inappropriate for 
use as an assembler format. It is designed to be read by a person,
not to be parsed by an assembler, so it has a number of
omissions and drawbacks. </p>

<p>
Internally, Sun has a Java assembler tool. In hindsight, the syntax used by their internal tool is nicer than
the Jasmin syntax. However, to my knowledge, their tool is still not widely available, nor is it a formally
supported part of the Sun JDK.
</p>

<h1>Update on Jasmin Today (2004) </h1>
 
Since Jasmin was written, it has become the de-facto standard assembly format for Java. It is used in dozens of compiler classes throughout the world, and has
been ported and cloned multiple times. For better or worse, Jasmin remains the original Java assembler.
<p>
[As an interesting comparison, Microsoft .NET shipped out-of-box with an 
assembler, a disassembler, a standard IL assembly format, and built-in libraries 
for code-genning (generating classes on the fly). It would be great if Sun was
as comprehensive in their support of the JVM].
</p>

<h1>What can I do with Jasmin?</h1>

To give you some ideas, below are some theoretical Jasmin users/uses.<p>

<h3>Teachers</h3>

If you are teaching a compilers course, you could have students
write a compiler which generates Jasmin assembly files,
and then assembles those files into Java class files. Then you
can integrate the advantages of the Virtual Machine (portability, 
the verifier, an object model...) into your courseware.<p>

<h3>Hobbyists</h3>

Jasmin lets you poke around in Java at the VM level, so that
you can gain a real understanding of how Java works and
what the Virtual Machine is like.<p>

<h3>System Implementors</h3>

If you are implementing a Java runtime system, Jasmin is 
an essential tool for generating test classes.<p>

<h3>Advanced Programmers</h3>

You could use Jasmin to write a critical class or method by 
hand (e.g. if you think that Java isn't doing things 
as well as it could). <p>

Alternatively, you could create a syntax extension to the
Java language which uses Jasmin (or JAS). <p>

<h3>Language Implementors</h3>

If you want to create an implementation of your
favorite programming language which targets the 
Virtual Machine, Jasmin may be a simpler approach than
writing a Java class file generator. This is especially
true if your compiler is implemented in something other
than Java, since you can create Java class files easily
without having to get involved in the details of the
binary file format.<p>

<h3>Security Wizards</h3>

Sun's claim that the Java class verifier protects you from
hostile programs is a pretty strong one. Jasmin lets you create
'hostile' class files and see if a Java implementation is really as 
secure as it should be. <p>

<hr><address>Copyright (c) Jonathan Meyer, July 1996</address>

<hr>
<a href="http://jasmin.sourceforge.net">Jasmin Home</a> |
<a href="http://www.cybergrain.com/">Jon Meyer's Home</a>

